\section{Code of conduct for
contributors}\label{code-of-conduct-for-contributors}

All contributors are encouraged to follow the code style
recommendations, and are required to follow the outlined branching
system. These guidelines are outlined in the following sections.

\section{Code style recommendations}\label{code-style-recommendations}

\subsection{Background}\label{background}

UxAS grew out of numerous research project and can still seem pieced
together. A similar style across the code base can make it easier to
navigate through the software. A list of our preferred style and best
practices are captured in two documents:

\begin{itemize}
\item
  \href{run:../../doxygen/files/CppProgrammingPracticesGuide.html}{Practices}
\item
  \href{run:../../doxygen/files/CppProgrammingStyleGuide.html}{Style}
\end{itemize}

The top guidelines are as follows:

\begin{itemize}
\item
  Use smart pointers, never bare
\item
  Use the full namespace for clarity
\item
  Minimize logic in constructors
\item
  Use C++11 types (e.g.~int32\_t rather than int)
\item
  Prefix member variables with `m\_'
\item
  Booleans start with a verb, i.e.~isOpen
\item
  Use abbreviations sparingly
\item
  Any complex logic should be in the .cpp file, not the .h
\item
  Use 4 spaces instead of tab
\item
  Append units to variable names (e.g.~distance\_m)
\item
  Braces on own lines
\item
  Keep parameters local, not in global files
\item
  Document with Doxygen comments
\end{itemize}

\section{Branch description and git flow
expectations}\label{branch-description-and-git-flow-expectations}

The OpenUxAS branching model addresses the following concerns:

\begin{itemize}
\item
  We have a stable branch that always builds and passes tests
\item
  Multiple collaborative teams can proceed with their development
  independently
\item
  Discrete features can be contributed to the main line of OpenUxAS
  development, and these can be integrated into other teams' ongoing
  work
\item
  Until OpenUxAS is public, all teams can use the \texttt{afrl-rq}
  organization's Travis-CI account for continuous integration
\end{itemize}

To address these concerns, OpenUxAS uses a variant on the
\href{http://nvie.com/posts/a-successful-git-branching-model/}{Git
Flow},
\href{https://docs.gitlab.com/ee/workflow/gitlab_flow.html}{GitLab
Flow}, and \href{https://guides.github.com/introduction/flow/}{GitHub
flow} models.

Because OpenUxAS does not yet have a fixed cycle of releases, we do not
need the additional complexity of \texttt{hotfix/} and \texttt{release/}
branches present in Git Flow. However, since a number of collaborating
teams work on OpenUxAS simultaneously, it makes sense to have long-lived
branches for each team, rather than only having feature branches and a
stable branch.

This README does not go into detail about the various Flow models, but
instead provides instructions for common scenarios. We encourage you to
read about the Flow models to get more of a sense for the ``why''; here
we are focusing on the ``how''.

\subsection{Quick Overview}\label{quick-overview}

The repository will typically have a branching structure like the
following:

\begin{itemize}
\item
  \texttt{master}
\item
  very stable, only updated by pull request from \texttt{develop}
\item
  \texttt{develop}
\item
  stable, only updated by pull request from feature branches
\item
  \texttt{teamA}
\item
  team branch for Team A
\item
  stable at the discretion of Team A
\item
  updated by merging in feature branches and \texttt{develop}
\item
  \texttt{teamA-feature1}
\item
  feature branch for Team A
\item
  when finished, merged into \texttt{develop} via pull request
\item
  \texttt{teamB}
\item
  \texttt{teamB-feature1}
\item
  etc.
\end{itemize}

\subsection{Team Branches}\label{team-branches}

The team branch is the branch off of which your team will work. It
serves the role of the \texttt{develop} branch of Git Flow or the
\texttt{master} branch of GitLab and GitHub Flow. This branch is never
intended to be directly merged back into \texttt{develop}, but feature
branches based off of it will be.

If you have experience with these models, this concept probably seems
odd. Eventually, we would like to replace these team branches with
entire repo forks for each team, but until OpenUxAS is public, this
would prevent forks from using the \texttt{afrl-rq} Travis-CI account.

\subsection{Create New Branch}\label{create-new-branch}

Start by creating a new branch that will serve as the active development
branch for your team. This step should only be necessary once for your
team; this branch is meant to be long-lived as opposed to a feature
branch that is quickly merged in and deleted.

\begin{verbatim}
$ git checkout develop
$ git checkout -b teamA
\end{verbatim}

\subsection{Updating}\label{updating}

You will want to regularly incorporate the latest changes from the
\texttt{develop} branch in your team branch. This reduces the pain when
merging your team's changes back into \texttt{develop}.

Start by making sure your local \texttt{develop} branch is up-to-date:

\begin{verbatim}
$ git checkout develop
$ git pull
\end{verbatim}

Then merge the updated \texttt{develop} with your team branch:

\begin{verbatim}
$ git checkout teamA
$ git merge develop
\end{verbatim}

\subsection{Feature Branches}\label{feature-branches}

Feature branches are shorter-lived branches meant to encompass a
particular effort or feature addition. These branches will be the means
for you to incorporate your team's changes into the main
\texttt{develop} branch via pull requests.

Feature branches will always be based off of your team branch, so if
your team branch has commits you would like to see in \texttt{develop},
you can simply create a new feature branch and begin the pull request
process right away.

\subsection{Naming}\label{naming}

To help the OpenUxAS maintainers know which branches belong to which
teams, feature branches should be named using your team name as a
prefix, for example \texttt{teamA-feature1}.

\subsection{Creating}\label{creating-1}

Create a feature branch by checking it out off of your team branch. Note
that it will save you some effort at the later merge to update your team
branch from \texttt{develop} first.

\begin{verbatim}
$ git checkout teamA
$ get checkout -b teamA/feature1
\end{verbatim}

\subsection{Merging to Team Branch}\label{merging-to-team-branch}

For a long-running feature branch, you may want to occasionally merge it
back into your team branch so it can be shared within your team before
it's ready to be merged into \texttt{develop}.

\begin{verbatim}
$ git checkout teamA
$ git merge teamA/feature1
\end{verbatim}

\subsection{Merging to develop}\label{merging-to-develop}

You cannot directly merge a feature branch into \texttt{develop},
because it is protected. Instead, open a pull request from the feature
branch into \texttt{develop}, and your changes will be merged after
review.

It is a good idea to update your team branch and delete your feature
branch once it is merged into \texttt{develop}.

\begin{verbatim}
$ git checkout develop
$ git pull
$ git checkout teamA
$ git merge develop
$ git push origin --delete teamA/feature1
$ git branch -d teamA/feature1
\end{verbatim}
